/*
 *  Copyright (C) 2010 Glauco
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package org.balisunrise.common;

import java.io.Serializable;
import org.balisunrise.common.listeners.BindingListener;

/**
 * Esta Interface faz um vinculo entre um objeto de origem e outro de destino.
 * O Vinculo pode ser mutuo, ou seja de source para targer e de target para
 * souce, ou pode ser exclusivo, apena source para target.
 * Esta Interface eh utlizada pelo BindingGroup, o qual controla um conjunto
 * de Bindings, ativando o vinculo e o desfazendo quando necessario.
 *
 * @author Glauco Knihs
 * @param <S> Source
 * @param <P> Tipo de dado da Propriedade do Source
 * @param <T> Target
 * @param <D> Tipo de dado da Propriedade do Target
 */
public interface Binding<S,P,T,D> extends Serializable{

    /**
     * Retorna a propriedade vinculada a partir do Source.
     */
    public String getSourceProperty();

    /**
     * Retorna a propriedade vinculada a partir do Target.
     */
    public String getTargetProperty();

    /**
     * Retorna o objeto Source do binding.
     */
    public S getSource();

    /**
     * Retorna o objeto Target do binding.
     */
    public T getTarget();

    /**
     * Set the Converter
     * @param converter the Converter
     * @see org.balisunrise.components.Converter
     */
    public void setConverter(Converter<P,D> converter);

    /**
     * Set the Validator
     * @param validator thr Validator
     * @see org.balisunrise.components.bindings.Validator
     */
    public void setValidator(Validator<P> validator);

    /**
     * Quando ativa por ter alguma propriedade da origem (<code>source</code>)
     * alterada deve ser enviado seu valor ao destino (<code>target</code>).
     * @return Verdadeiro caso a sincronização ocorreu corretamente. Falso caso
     * contrário.
     */
    public boolean sourcePropertyChanged();

    /**
     * Quando ativa por ter alguma propriedade do destino (<code>target</code>)
     * alterada deve ser enviado seu valor a origem (<code>source</code>).
     * @return Verdadeiro caso a sincronização ocorreu corretamente. Falso caso
     * contrário.
     */
    public boolean targerPropertyChanged();

    /**
     * Ativa o vinculo entre o source e o target.
     */
    public void bind();

    /**
     * Desfaz o vinculo entre o source e o target.
     */
    public void unBind();

    /**
     * Sincroniza o valor da propriedade do source com a propriedade do target.
     * @return Resultado da sincronização.
     */
    public SyncResult syncSourceToTarget();

    /**
     * Sincroniza o valor da propriedade do target com a propriedade do source.
     * @return Resultado da sincronização.
     */
    public SyncResult syncTargetToSource();

    public P getSourcePropertyValue() throws BindingException;

    public D getTargetPropertyValue() throws BindingException;

    public D convertToTarget(P value) throws Exception;

    public P convertToSource(D value) throws Exception;

    public void validate(P value) throws Exception;

    public void setSourcePropertyValue(P value) throws BindingException, Exception;

    public void setTargetPropertyValue(D value) throws BindingException, Exception;

    public BindingListener[] getListeners(BindingListener[] a);

    public BindingListener removeListener(int index);

    public boolean removeListener(BindingListener o);

    public void addListener(int index, BindingListener element);

    public boolean addListener(BindingListener e);
    
}
